Skip to main content

Factory

note

Each integrated chain has its own factory contract. These contracts are created by Euclid whenever an integration with a new chain occurs. You can read about the factory architecture here.

Execute Messages​

List of user-facing execute methods that can be called on the Solidity Factory contract.

Swap​

Performs a swap from asset_in into asset_out, optionally distributing the output across one or more recipients.

function swap(
    TokenWithDenom calldata asset_in,
    uint256 amount_in,
    string calldata asset_out,
    uint256 min_amount_out,
    NextSwapPair[] calldata swaps,
    Recipient[] memory recipients,
    PartnerFee memory partner_fee,
    CrossChainConfig calldata cross_chain_config
) external payable;
{
  "swap": {
    "asset_in": {
      "token": "usdc",
      "token_type": {
        "token_type": "smart",
        "native_denom": "",
        "erc20_address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831"
      }
    },
    "amount_in": "1000000",
    "asset_out": "usdt",
    "min_amount_out": "998000",
    "swaps": [
      {
        "token_in": "usdc",
        "token_out": "usdt",
        "test_fail": false
      }
    ],
    "recipients": [
      {
        "recipient": {
          "chain_uid": "arbitrum",
          "sender": "0x7a93d4bc1f1e51d3b8a912b1e6d2a5a13c44b9f1"
        },
        "amount": {
          "limit_type": "dynamic",
          "value": "0"
        },
        "denom": {
          "token_type": "smart",
          "native_denom": "",
          "erc20_address": "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9"
        },
        "forwarding_message": "0x",
        "unsafe_refund_as_voucher": false
      }
    ],
    "partner_fee": {
      "partner_fee_bps": 30,
      "recipient": "0x4f2a8cc4b36a1de5f5df9b3a1b09c2d893a8e11f"
    },
    "cross_chain_config": {
      "timeout": 60,
      "ack_response": "0x",
      "meta": "swap-route-usdc-usdt"
    }
  }
}
FieldTypeDescription
asset_inTokenWithDenomThe token being swapped in.
amount_inuint256Amount of the input asset.
asset_outstringThe token id being swapped out.
min_amount_outuint256Minimum amount of the output asset for the swap to be considered a success. Used to specify maximum slippage accepted.
swapsNextSwapPair[]The different swaps to get from asset_in to asset_out. This could be a direct swap or multiple swaps. For example, if swapping from token A to B, the swaps can be A -> B directly, or A -> C then C -> D then D -> B. Usually the most efficient route is used.
recipientsRecipient[]A set of recipients to specify where the asset_out should be released. Recipient amount constraints define how much should be released to each destination.
partner_feePartnerFeeOptional partner fee information for swaps. The maximum fee that can be set is 30 (0.3%).
cross_chain_configCrossChainConfigCross-chain timeout/ack/meta controls for this request.
note
  • Swap paths are usually determined off-chain (for example by routing services) and passed in swaps.

With the following structs:

/// The next token pair in the swap route
struct NextSwapPair {
    string token_in;
    string token_out;
    // Internal testing flag, keep false in production usage.
    bool test_fail;
}

/// The percentage of the fee for the platform. Specified in basis points:
/// 1 = 0.01%, 10000 = 100%
struct PartnerFee {
    // Cannot be set greater than 30 (0.3%)
    uint64 partner_fee_bps;
    // Address to receive the fee.
    address recipient;
}

DepositToken​

Exchanges deposited native/ERC20 tokens for voucher balances/releases using recipient rules.

function depositToken(
    TokenWithDenom calldata asset_in,
    uint256 amount_in,
    Recipient[] memory recipients,
    CrossChainConfig calldata cross_chain_config
) external payable;
{
  "depositToken": {
    "asset_in": {
      "token": "eth",
      "token_type": {
        "token_type": "native",
        "native_denom": "eth",
        "erc20_address": ""
      }
    },
    "amount_in": "1000000000000000000",
    "recipients": [
      {
        "recipient": {
          "chain_uid": "base",
          "sender": "0x1111222233334444555566667777888899990000"
        },
        "amount": {
          "limit_type": "equal",
          "value": "1000000000000000000"
        },
        "denom": {
          "token_type": "voucher",
          "native_denom": "",
          "erc20_address": ""
        },
        "forwarding_message": "0x",
        "unsafe_refund_as_voucher": false
      }
    ],
    "cross_chain_config": {
      "timeout": 60,
      "ack_response": "0x",
      "meta": "deposit-eth"
    }
  }
}
FieldTypeDescription
asset_inTokenWithDenomThe asset being exchanged.
amount_inuint256The amount of tokens being exchanged. Should match attached funds to the message when native funds are used.
recipientsRecipient[]Recipients that define who should receive resulting vouchers/releases and under what constraints.
cross_chain_configCrossChainConfigCross-chain timeout/ack/meta options.

TransferVoucher​

Transfers voucher balances and optionally releases them based on recipient settings.

function transferVoucher(
    string calldata token_id,
    uint256 amount,
    CrossChainUser memory from,
    Recipient[] memory recipients,
    CrossChainConfig calldata cross_chain_config
) external payable;
{
  "transferVoucher": {
    "token_id": "usdc",
    "amount": "500000",
    "from": {
      "chain_uid": "arbitrum",
      "sender": "0x7a93d4bc1f1e51d3b8a912b1e6d2a5a13c44b9f1"
    },
    "recipients": [
      {
        "recipient": {
          "chain_uid": "optimism",
          "sender": "0x2222333344445555666677778888999900001111"
        },
        "amount": {
          "limit_type": "less_than_or_equal",
          "value": "500000"
        },
        "denom": {
          "token_type": "smart",
          "native_denom": "",
          "erc20_address": "0x754704bc059f8c67012fed69bc8a327a5aafb603"
        },
        "forwarding_message": "0x",
        "unsafe_refund_as_voucher": false
      }
    ],
    "cross_chain_config": {
      "timeout": 60,
      "ack_response": "0x",
      "meta": "transfer-voucher"
    }
  }
}
FieldTypeDescription
token_idstringToken id of the voucher balance to transfer.
amountuint256Amount of voucher balance to transfer.
fromCrossChainUserSource user for this transfer flow.
recipientsRecipient[]Destination recipients and release constraints.
cross_chain_configCrossChainConfigCross-chain timeout/ack/meta options.

Add Liquidity​

Requests adding liquidity for a pair using token amounts and denom details.

function add_liquidity(
    PairWithDenomAndAmount calldata pair_with_denom_and_amount,
    uint64 slippage_tolerance_bps,
    CrossChainConfig calldata cross_chain_config
) external payable;
{
  "add_liquidity": {
    "pair_with_denom_and_amount": {
      "token_1": {
        "token": "usdc",
        "amount": "1000000",
        "token_type": {
          "token_type": "smart",
          "native_denom": "",
          "erc20_address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831"
        }
      },
      "token_2": {
        "token": "usdt",
        "amount": "1000000",
        "token_type": {
          "token_type": "smart",
          "native_denom": "",
          "erc20_address": "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9"
        }
      }
    },
    "slippage_tolerance_bps": 300,
    "cross_chain_config": {
      "timeout": 60,
      "ack_response": "0x",
      "meta": "add-liquidity"
    }
  }
}
FieldTypeDescription
pair_with_denom_and_amountPairWithDenomAndAmountThe tokens to add liquidity to, with the amount for each.
slippage_tolerance_bpsuint64The amount of slippage tolerated. If the slippage amount surpasses the specified amount, the request will fail and the user receives back the tokens. Specified as basis points.
cross_chain_configCrossChainConfigCross-chain timeout/ack/meta options.

Remove Liquidity​

Requests removing liquidity from a pool and releasing output to a target recipient.

function remove_liquidity(
    Pair calldata pair,
    uint256 lp_allocation,
    CrossChainUser memory recipient,
    CrossChainConfig calldata cross_chain_config
) external payable;
{
  "remove_liquidity": {
    "pair": {
      "token_1": "usdc",
      "token_2": "usdt"
    },
    "lp_allocation": "1000000000000000000",
    "recipient": {
      "chain_uid": "base",
      "sender": "0x3333444455556666777788889999000011112222"
    },
    "cross_chain_config": {
      "timeout": 60,
      "ack_response": "0x",
      "meta": "remove-liquidity"
    }
  }
}
FieldTypeDescription
pairPairThe pair of tokens for which liquidity is being removed.
lp_allocationuint256The amount of LP tokens being returned to the pool.
recipientCrossChainUserDestination user/chain for release.
cross_chain_configCrossChainConfigCross-chain timeout/ack/meta options.

Request Pool Creation​

Requests creation of a new pool with pair settings, pool config, and LP token metadata.

function request_pool_creation(
    PairWithDenomAndAmount calldata pair_with_denom_and_amount,
    PoolConfig calldata pool_config,
    string calldata lp_token_name,
    string memory lp_token_symbol,
    uint8 lp_token_decimals,
    uint64 slippage_tolerance_bps,
    CrossChainConfig calldata cross_chain_config
) external payable;
{
  "request_pool_creation": {
    "pair_with_denom_and_amount": {
      "token_1": {
        "token": "usdc",
        "amount": "2000000",
        "token_type": {
          "token_type": "smart",
          "native_denom": "",
          "erc20_address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831"
        }
      },
      "token_2": {
        "token": "usdt",
        "amount": "2000000",
        "token_type": {
          "token_type": "smart",
          "native_denom": "",
          "erc20_address": "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9"
        }
      }
    },
    "pool_config": {
      "pool_type": "stable",
      "amp_factor": "1200"
    },
    "lp_token_name": "USDC-USDT LP",
    "lp_token_symbol": "USDCUSDT-LP",
    "lp_token_decimals": 18,
    "slippage_tolerance_bps": 200,
    "cross_chain_config": {
      "timeout": 120,
      "ack_response": "0x",
      "meta": "create-pool"
    }
  }
}
FieldTypeDescription
pair_with_denom_and_amountPairWithDenomAndAmountThe token pair to request creating a new pool for.
pool_configPoolConfigThe pool configuration type (for example stable with amplification factor, or constant product).
lp_token_namestringLP token name.
lp_token_symbolstringLP token symbol.
lp_token_decimalsuint8LP token decimals.
slippage_tolerance_bpsuint64Allowed slippage amount in basis points (bps) during pool creation.
cross_chain_configCrossChainConfigCross-chain timeout/ack/meta options.

Query Messages​

List of read-only methods exposed by the Solidity Factory contract.

get_factory_state​

Returns the factory state configuration.

function get_factory_state() external pure returns (FactoryStorage.Layout memory);
{
  "method": "get_factory_state",
  "params": []
}

The query returns the following response:

struct Layout {
    string chain_uid;
    string router_address;
    string native_denom;
    address fund_manager;
    address relayer;
}
{
  "chain_uid": "arbitrum",
  "router_address": "vsl.router",
  "native_denom": "eth",
  "fund_manager": "0x8f8c6f1f7f9f4d7f8a7a9f8b6a6b4e3d2c1b0a9f",
  "relayer": "0x1234567890abcdef1234567890abcdef12345678"
}
FieldTypeDescription
chain_uidstringChain UID where this factory is deployed.
router_addressstringRouter address/port identifier used for cross-chain relay.
native_denomstringNative denom configured for this chain.
fund_manageraddressFund manager contract address.
relayeraddressRelayer contract address.

get_factory_modules​

Returns the module implementation addresses configured in factory.

function get_factory_modules() external view returns (FactoryModules memory);
{
  "method": "get_factory_modules",
  "params": []
}

The query returns the following response:

struct FactoryModules {
    address cross_chain_module;
    address pool_module;
    address swap_module;
    address token_module;
}
{
  "cross_chain_module": "0x1111111111111111111111111111111111111111",
  "pool_module": "0x2222222222222222222222222222222222222222",
  "swap_module": "0x3333333333333333333333333333333333333333",
  "token_module": "0x4444444444444444444444444444444444444444"
}
FieldTypeDescription
cross_chain_moduleaddressCross-chain module implementation address.
pool_moduleaddressPool module implementation address.
swap_moduleaddressSwap module implementation address.
token_moduleaddressToken module implementation address.

get_token_escrow​

Returns escrow contract address for a token id.

function get_token_escrow(string calldata token_id) external view returns (address);
{
  "method": "get_token_escrow",
  "params": ["usdc"]
}

The query returns the following response:

address escrow_address;
"0x5555555555555555555555555555555555555555"
FieldTypeDescription
token_idstringToken id used to fetch escrow.
escrow_addressaddressEscrow contract address for that token id.

get_pool_vlp​

Returns VLP key/address string for a pool key.

function get_pool_vlp(string calldata pool_key) public view returns (string memory);
{
  "method": "get_pool_vlp",
  "params": ["usdc:usdt"]
}

The query returns the following response:

string vlp_key;
"arbitrum.0x9f3a31b1a08e2b10f65d68edca1d1a4956b4f6d1"
FieldTypeDescription
pool_keystringPool key (for example token_1:token_2).
vlp_keystringVLP key/address string mapped to that pool.

get_vlp_lp_address​

Returns LP token contract address for a VLP key.

function get_vlp_lp_address(string calldata vlp_key) public view returns (address);
{
  "method": "get_vlp_lp_address",
  "params": ["arbitrum.0x9f3a31b1a08e2b10f65d68edca1d1a4956b4f6d1"]
}

The query returns the following response:

address lp_token_address;
"0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d"
FieldTypeDescription
vlp_keystringVLP key string returned by get_pool_vlp.
lp_token_addressaddressLP token contract address.